<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Synchronizing with a master</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="rep.html" title="Chapter 13.  Berkeley DB Replication" />
    <link rel="prev" href="rep_elect.html" title="Elections" />
    <link rel="next" href="rep_init.html" title="Initializing a new site" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Synchronizing with a
        master</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="rep_elect.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 13.  Berkeley DB Replication </th>
          <td width="20%" align="right"> <a accesskey="n" href="rep_init.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="rep_mastersync"></a>Synchronizing with a
        master</h2>
          </div>
        </div>
      </div>
      <div class="toc">
        <dl>
          <dt>
            <span class="sect2">
              <a href="rep_mastersync.html#rep_delay_sync">Delaying client synchronization</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="rep_mastersync.html#rep_c2c_sync">Client-to-client synchronization</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="rep_mastersync.html#idm140526453549456">Blocked client operations</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="rep_mastersync.html#idm140526453475616">Clients too far out-of-date to synchronize</a>
            </span>
          </dt>
        </dl>
      </div>
      <p>
        When a client detects a new replication group master, the
        client must synchronize with the new master before the client
        can process new database changes. Synchronizing is a
        heavyweight operation which can place a burden on both the
        client and the master. There are several controls an
        application can use to reduce the synchronization
        burden.
    </p>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="rep_delay_sync"></a>Delaying client synchronization</h3>
            </div>
          </div>
        </div>
        <p>
            When a replication group has a new master, either as
            specified by the application or as a result of winning an
            election, all clients in the replication group must
            synchronize with the new master. This can strain the
            resources of the new master since a large number of
            clients may be attempting to communicate with and transfer
            records from the master. Client applications wanting to
            delay client synchronization should call the <a href="../api_reference/C/repconfig.html" class="olink">DB_ENV-&gt;rep_set_config()</a>
            method with the <a href="../api_reference/C/repconfig.html#config_DB_REP_CONF_DELAYCLIENT" class="olink">DB_REP_CONF_DELAYCLIENT</a> flag. The
            application will be notified of the establishment of the
            new master as usual, but the client will not proceed to
            synchronize with the new master.
        </p>
        <p>
            Applications learn of a new master via the
            <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_NEWMASTER" class="olink">DB_EVENT_REP_NEWMASTER</a> event.
        </p>
        <p>
            Client applications choosing to delay synchronization in
            this manner are responsible for synchronizing the client
            environment at some future time using the <a href="../api_reference/C/repsync.html" class="olink">DB_ENV-&gt;rep_sync()</a>
            method.
        </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="rep_c2c_sync"></a>Client-to-client synchronization</h3>
            </div>
          </div>
        </div>
        <p>
            Instead of synchronizing with the new master, it is
            sometimes possible for a client to synchronize with
            another client. Berkeley DB initiates synchronization at
            the client by sending a request message via the transport
            call-back function of the communication infrastructure.
            The message is destined for the master site, but is also
            marked with a <a href="../api_reference/C/reptransport.html#transport_DB_REP_ANYWHERE" class="olink">DB_REP_ANYWHERE</a> flag. The application may
            choose to send such a request to another client, or to
            ignore the flag, sending it to its indicated
            destination.
        </p>
        <p>
            Furthermore, when the other client receives such a
            request it may be unable to satisfy it. In this case it
            will reply to the requesting client, telling it that it is
            unable to provide the requested information. The
            requesting client will then re-issue the request.
            Additionally, if the original request never reaches the
            other client, the requesting client will again re-issue
            the request. In either of these cases the message will be
            marked with the <a href="../api_reference/C/reptransport.html#transport_DB_REP_REREQUEST" class="olink">DB_REP_REREQUEST</a> flag. The application
            may continue trying to find another client to service the
            request, or it may give up and simply send it to the
            master (that is, the environment ID explicitly specified
            to the transport function).
        </p>
        <p> 
            Replication Manager allows an application to designate
            one or more remote sites (called its "peers") to receive
            client-to-client requests. You do this by setting the
            <code class="literal">DB_REPMGR_PEER</code> parameter using the
            <a href="../api_reference/C/dbsite_set_config.html" class="olink">DB_SITE-&gt;set_config()</a> method. Replication Manager always
            tries to send requests marked with the <a href="../api_reference/C/reptransport.html#transport_DB_REP_ANYWHERE" class="olink">DB_REP_ANYWHERE</a>
            flag to a peer, if available. However, a
            <a href="../api_reference/C/reptransport.html#transport_DB_REP_REREQUEST" class="olink">DB_REP_REREQUEST</a> message is always handled by requesting
            the information from the master. A view can serve as a
            peer, but a partial view is more likely to be missing
            requested information, which will then be requested from
            the master.
        </p>
        <p>
            Base API applications have complete freedom in choosing
            where to send these <a href="../api_reference/C/reptransport.html#transport_DB_REP_ANYWHERE" class="olink">DB_REP_ANYWHERE</a> requests, and in
            deciding how to handle <a href="../api_reference/C/reptransport.html#transport_DB_REP_REREQUEST" class="olink">DB_REP_REREQUEST</a>.
        </p>
        <p>
            The delayed synchronization and client-to-client
            synchronization features allow applications to do load
            balancing within replication groups. For example, consider
            a replication group with 5 sites, A, B, C, D and E. Site E
            just crashed, and site A was elected master. Sites C and D
            have been configured for delayed synchronization. When
            site B is notified that site A is a new master, it
            immediately synchronizes. When B finishes synchronizing
            with the master, the application calls the <a href="../api_reference/C/repsync.html" class="olink">DB_ENV-&gt;rep_sync()</a>
            method on sites C and D to cause them to synchronize as
            well. Sites C and D (and E, when it has finished
            rebooting) can send their requests to site B, and B then
            bears the brunt of the work and network traffic for
            synchronization, making master site A available to handle
            the normal application load and any write requests paused
            by the election.
        </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idm140526453549456"></a>Blocked client operations</h3>
            </div>
          </div>
        </div>
        <p>
            Clients in the process of synchronizing with the master
            block access to Berkeley DB operations during some parts
            of that process. By default, most Berkeley DB methods will
            block until client synchronization is complete, and then
            the method call proceeds.
        </p>
        <p>
            Client applications which cannot wait and would prefer
            an immediate error return instead of blocking, should call
            the <a href="../api_reference/C/repconfig.html" class="olink">DB_ENV-&gt;rep_set_config()</a> method with the <a href="../api_reference/C/repconfig.html#config_DB_REP_CONF_NOWAIT" class="olink">DB_REP_CONF_NOWAIT</a> flag.
            This configuration causes <a href="../api_reference/C/db.html" class="olink">DB</a> method calls to immediately
            return a <a href="../api_reference/C/dbput.html#dbput_DB_REP_LOCKOUT" class="olink">DB_REP_LOCKOUT</a> error instead of blocking, if
            the client is currently synchronizing with the
            master.
        </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idm140526453475616"></a>Clients too far out-of-date to synchronize</h3>
            </div>
          </div>
        </div>
        <p>
            Clients attempting to synchronize with the master may
            discover that synchronization is not possible because the
            client no longer has any overlapping information with the
            master site. By default, the master and client
            automatically detect this state and perform an internal
            initialization of the client. Because internal
            initialization requires transfer of entire databases to
            the client, it can take a relatively long period of time
            and may require database handles to be reopened in the
            client applications.
        </p>
        <p>
            Client applications which cannot wait or would prefer to
            do a hot backup instead of performing internal
            initialization, should call the <a href="../api_reference/C/repconfig.html" class="olink">DB_ENV-&gt;rep_set_config()</a> method to turn
            off the <a href="../api_reference/C/repconfig.html#config_DB_REP_CONF_AUTOINIT" class="olink">DB_REP_CONF_AUTOINIT</a> flag. Turning off this
            configuration flag causes Berkeley DB to return
            <a href="../api_reference/C/repmessage.html#repmsg_DB_REP_JOIN_FAILURE" class="olink">DB_REP_JOIN_FAILURE</a> to the application instead of
            performing internal initialization.
        </p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="rep_elect.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="rep.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="rep_init.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Elections </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Initializing a new site</td>
        </tr>
      </table>
    </div>
  </body>
</html>
